home *** CD-ROM | disk | FTP | other *** search
/ Apple WWDC 1996 / WWDC96_1996 (CD).toast / Technology Materials / MacOS 8 Resources / Developer Tools / Mac OS 8 Interfaces & Libraries / Interfaces / CIncludes / CoachMarks.h < prev    next >
C/C++ Source or Header  |  1996-05-01  |  8KB  |  265 lines
  1. /*
  2.      File:        CoachMarks.h
  3.  
  4.      Contains:    Public CoachMark programming interface.
  5.  
  6.      Version:    Technology:    Copland
  7.                  Release:    Universal Interfaces 3.0d3 on Copland DR1
  8.  
  9.      Copyright:    © 1984-1996 by Apple Computer, Inc.  All rights reserved.
  10.  
  11.      Bugs?:        If you find a problem with this file, send the file and version
  12.                  information (from above) and the problem description to:
  13.  
  14.                      Internet:    apple.bugs@applelink.apple.com
  15.                      AppleLink:    APPLE.BUGS
  16.  
  17. */
  18. #ifndef __COACHMARKS__
  19. #define __COACHMARKS__
  20.  
  21. #ifndef __TYPES__
  22. #include <Types.h>
  23. #endif
  24. #ifndef __SOUND__
  25. #include <Sound.h>
  26. #endif
  27. #ifndef __WINDOWS__
  28. #include <Windows.h>
  29. #endif
  30. #ifndef __HIWINDOWTYPES__
  31. #include <HIWindowTypes.h>
  32. #endif
  33.  
  34. #ifdef __cplusplus
  35. extern "C" {
  36. #endif
  37.  
  38. #if PRAGMA_IMPORT_SUPPORTED
  39. #pragma import on
  40. #endif
  41.  
  42. #if PRAGMA_ALIGN_SUPPORTED
  43. #pragma options align=mac68k
  44. #endif
  45.  
  46. #if FOR_SYSTEM8_COOPERATIVE
  47. /*
  48.  Macros ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
  49.  For X's, 2-bit groups specify the curvature of each leg
  50. */
  51. #define XMarkTopLeftToBottomRight(curvature)    (curvature) 
  52. #define XMarkTopRightToBottomLeft(curvature)    (curvature << 2)
  53. /*
  54.  Attributes ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
  55.  animation speeds
  56. */
  57.  
  58. enum {
  59.     kCoachMarkFastest            = 0,
  60.     kCoachMarkSlowest            = 31
  61. };
  62.  
  63. /* sloppiness*/
  64.  
  65. enum {
  66.     kPerfectCoachMark            = 0,
  67.     kSloppyCoachMark            = 100
  68. };
  69.  
  70. /* translucency*/
  71.  
  72. enum {
  73.     kMaxCoachMarkWeight            = 100,
  74.     kDefaultCoachMarkRegularWeight = 75,
  75.     kDefaultCoachMarkHiddenWeight = 25
  76. };
  77.  
  78. /* stroke width*/
  79.  
  80. enum {
  81.     kDefaultCircleCoachMarkThickness = 12,
  82.     kDefaultUnderlineCoachMarkThickness = 8,
  83.     kDefaultXCoachMarkThickness    = 15,
  84.     kDefaultArrowCoachMarkThickness = 7,
  85.     kDefaultHighlighterCoachMarkThickness = 5
  86. };
  87.  
  88. /* Selectors ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------*/
  89.  
  90. enum {
  91.     kCircleCoachMark            = 1,
  92.     kUnderlineCoachMark            = 2,
  93.     kXCoachMark                    = 3,
  94.     kArrowCoachMark                = 4,
  95.     kHighlighterCoachMark        = 5,
  96.     kNumCoachMarkTypes            = 5
  97. };
  98.  
  99. typedef UInt32 CoachMarkType;
  100.  
  101. enum {
  102.     kCoachMarkStraight            = 0,
  103.     kCoachMarkCurvesUp            = 1,
  104.     kCoachMarkCurvesDown        = 2
  105. };
  106.  
  107. typedef UInt32 CoachMarkCurvature;
  108. /*
  109.  Flags ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
  110.  theme element inheritance flags -- is "heritage" and "inherit" too wordy?  Could use a scheme based on the word "trait"
  111. */
  112.  
  113. enum {
  114.     kCoachOverrideThemeNothing    = 0,
  115.     kCoachOverrideThemeColor    = (1 << 0),
  116.     kCoachOverrideThemeOpacity    = (1 << 1),
  117.     kCoachOverrideThemeSloppiness = (1 << 2),
  118.     kCoachOverrideThemeStrokeWidth = (1 << 3),
  119.     kCoachOverrideAllThemeTraits = 0xFFFFFFFF
  120. };
  121.  
  122. typedef UInt32 CoachThemeOverrideFlags;
  123.  
  124. enum {
  125.     kCoachMarkDefaultAnimation    = 0
  126. };
  127.  
  128. typedef UInt32 CoachAnimationType;
  129. /*
  130.  In which direction should the animation go? For an arrow or underline
  131.  this is inherent in the geometry. For the others, some bit flags:
  132. */
  133.  
  134. enum {
  135.     kCoachMarkDefaultDirection    = 0,                            /* for circle: */
  136.     kCoachMarkClockwise            = 0x0000,
  137.     kCoachMarkCounterClockwise    = 0x0001,                        /* X stroke direction: */
  138.     kCoachMarkTopLeftToBottomRightMask = 0x0000,
  139.     kCoachMarkBottomRightToTopLeftMask = 0x0004,                /* X stroke direction: */
  140.     kCoachMarkTopRightToBottomLeftMask = 0x0000,
  141.     kCoachMarkBottomLeftToTopRightMask = 0x0008,                /* which X stroke is first: */
  142.     kCoachMarkTopLeftToBottomRightFirstMask = 0x0000,
  143.     kCoachMarkTopRightToBottomLeftFirstMask = 0x0010
  144. };
  145.  
  146. typedef UInt32 CoachDirection;
  147. /* to specify how to erase a coach mark*/
  148.  
  149. enum {
  150.     kCoachMarkDefaultErase        = 0
  151. };
  152.  
  153. typedef UInt32 CoachMarkEraseOptions;
  154. /*
  155.  Structures ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
  156.  opaque reference to a coach mark
  157. */
  158. typedef struct OpaqueCoachMarkRef* CoachMarkRef;
  159. /* CoachMarkRec specifies the appearance of a CoachMark*/
  160. struct CoachMarkRec {
  161.     CoachMarkType                     markType;                    /* which shape of mark?*/
  162.     CoachThemeOverrideFlags         themeOverrides;                /* which values do we get from the theme? */
  163.     RGBColor                         color;                        /* what color shall the CoachMark be?*/
  164.     Handle                             sound;                        /* sound to be played upon drawing the coachmark (*** Doesn't work in D11)*/
  165.     UInt16                             regularPercentage;            /* 0..100    - opacity as drawn within the specified grafport*/
  166.     UInt16                             hiddenPercentage;            /* 0..100    - opacity as drawn outside the specified grafport*/
  167.     UInt16                             sloppiness;                    /* 0..100*/
  168.     UInt16                             thickness;                    /* in pixels*/
  169.     CoachMarkCurvature                 curvature;                    /* direction of bulge for line-like marks*/
  170. };
  171. typedef struct CoachMarkRec CoachMarkRec;
  172.  
  173. /* CoachMarkAnimation specifies the appearance of a coach mark's animation*/
  174. struct CoachMarkAnimation {
  175.     CoachAnimationType                 effectType;
  176.     UInt32                             speed;
  177.     CoachDirection                     direction;
  178. };
  179. typedef struct CoachMarkAnimation CoachMarkAnimation;
  180.  
  181. /*
  182.  The Freaky Good Stuff --------------------------------------------------------------------------------------------------------------------------------------------------------------
  183.  Creation/destruction
  184. */
  185. extern OSStatus NewCoachMarkRef(const CoachMarkRec *appearance, CoachMarkRef *newCoachMark);
  186.  
  187. extern OSStatus GetNewCoachMarkRef(SInt16 resID, CoachMarkRef *newMark);
  188.  
  189. extern OSStatus DisposeCoachMark(CoachMarkRef theMark);
  190.  
  191. /* To specify geometry*/
  192. extern OSStatus CoachRectOnWindow(CoachMarkRef mark, HIWindow *window, const Rect *localRect);
  193.  
  194. extern OSStatus CoachGlobalRect(CoachMarkRef mark, const Rect *globalRect);
  195.  
  196. extern OSStatus CoachStrokeOnWindow(CoachMarkRef theMark, HIWindow *window, const Point *localSource, const Point *localDest);
  197.  
  198. extern OSStatus CoachGlobalStroke(CoachMarkRef theMark, const Point *globalSource, const Point *globalDest);
  199.  
  200. /* Accessors*/
  201. extern CoachMarkType GetCoachMarkType(CoachMarkRef theMark);
  202.  
  203. extern HIWindow *GetCoachMarkWindow(CoachMarkRef theMark);
  204.  
  205. extern OSStatus GetCoachMarkRect(CoachMarkRef mark, Rect *globalRect);
  206.  
  207. extern OSStatus GetCoachMarkStroke(CoachMarkRef theMark, Point *globalSource, Point *globalDest);
  208.  
  209. extern OSStatus SetCoachMarkColor(CoachMarkRef theMark, const RGBColor *color);
  210.  
  211. extern OSStatus GetCoachMarkColor(CoachMarkRef theMark, RGBColor *color);
  212.  
  213. extern OSStatus SetCoachMarkRegularWeight(CoachMarkRef theMark, UInt16 weight);
  214.  
  215. extern UInt16 GetCoachMarkRegularWeight(CoachMarkRef theMark);
  216.  
  217. extern OSStatus SetCoachMarkHiddenWeight(CoachMarkRef theMark, UInt16 weight);
  218.  
  219. extern UInt16 GetCoachMarkHiddenWeight(CoachMarkRef theMark);
  220.  
  221. extern OSStatus SetCoachMarkThickness(CoachMarkRef theMark, UInt16 thickness);
  222.  
  223. extern UInt16 GetCoachMarkThickness(CoachMarkRef theMark);
  224.  
  225. extern OSStatus SetCoachMarkSloppiness(CoachMarkRef theMark, UInt16 sloppiness);
  226.  
  227. extern UInt16 GetCoachMarkSloppiness(CoachMarkRef theMark);
  228.  
  229. extern OSStatus SetCoachMarkCurvature(CoachMarkRef theMark, CoachMarkCurvature curvature);
  230.  
  231. extern CoachMarkCurvature GetCoachMarkCurvature(CoachMarkRef theMark);
  232.  
  233. extern OSStatus SetCoachMarkThemeOverrides(CoachMarkRef theMark, CoachThemeOverrideFlags inHeritage);
  234.  
  235. extern OSStatus GetCoachMarkThemeOverrides(CoachMarkRef theMark, CoachThemeOverrideFlags *outHeritage);
  236.  
  237. /*
  238.  Drawing, animation, erasing
  239.  CoachMarkInteraction is synchronous and applies globallly, the other three are not and require windows
  240. */
  241. extern OSStatus CoachMarkInteraction(CoachMarkRef theMark, const CoachMarkAnimation *effect);
  242.  
  243. extern OSStatus AnimateCoachMark(CoachMarkRef theMark, const CoachMarkAnimation *effect);
  244.  
  245. extern OSStatus DrawCoachMark(CoachMarkRef theMark);
  246.  
  247. extern OSStatus EraseCoachMark(CoachMarkRef theMark, CoachMarkEraseOptions options);
  248.  
  249. #endif
  250.  
  251. #if PRAGMA_ALIGN_SUPPORTED
  252. #pragma options align=reset
  253. #endif
  254.  
  255. #if PRAGMA_IMPORT_SUPPORTED
  256. #pragma import off
  257. #endif
  258.  
  259. #ifdef __cplusplus
  260. }
  261. #endif
  262.  
  263. #endif /* __COACHMARKS__ */
  264.  
  265.